Skip to content

8.3. Templates

When is a template worth maintaining?

A template pays off when several agents need the same packaging, validation, image, protocol, security, and delivery contracts. For one derivative, a focused fork is simpler. A generator is another product with versions, migrations, tests, and support obligations.

This repository is a reference implementation, not currently a published project generator.

What should be parameterized?

  • Distribution/module/agent/display names.
  • Provider, model, direct/gateway base URL, and optional cloud profile.
  • Tool/skill/data packages and ownership.
  • A2A advertised address and call budget.
  • OCI image, namespace, registry, GCP project/region/bucket values.
  • MLflow experiment/service identity and retention.

Never template a credential, personal path, existing trace/database, or hard-coded cloud identity.

What should remain invariant?

  • src/ package layout and locked dependency workflow.
  • one mise run task vocabulary for hooks and CI.
  • typed settings/domain/tool boundaries.
  • immutable seed versus writable runtime state.
  • direct local reads versus governed MCP reads and confirmed writes.
  • offline branch-covered tests and deterministic adversarial cases.
  • non-root image, explicit health/resources/storage/network policy.
  • docs/source synchronization and OSS boundary language.

Which OSS templating tool should you use?

Copier is an open-source option when generated projects must receive template updates. Cookiecutter is a simpler open-source generator for create-once scaffolds. Review licenses/dependencies and pin the selected tool; neither is required by this repository.

How do you validate a generated project?

Generate into a disposable directory and run its install, format, check, test, image build/scan, Kustomize render, secret scan, and docs link checks. Search for unreplaced template delimiters, course-specific names, email/project ids, and fixture data. The generated repository must be usable without access to the original workspace.

What is the template checkpoint?

Write a parameter table and expected generated tree, then prove two different parameter sets both pass the complete gate. Do not publish the generator until update/migration behavior and license notices are tested.